Python API Reference

This page documents the Python classes, interfaces, methods, and functions in void_builder.

Module: void_builder.core.config_loader

Class Config(data)

Data wrapper for configuration dictionaries with dot-notation access.

Methods

  • get(path: str, default: Any = None) -> Any: Retrieves configuration value using dot notation (e.g., system.iso_label).

  • to_dict() -> Dict[str, Any]: Returns raw dictionary underlying data.

Class ConfigAssembler(config_root)

Composition brain that merges global manifests and component profiles.

Parameters

  • config_root (str or Path): Directory containing configuration subfolders.

Methods

  • assemble(target_arch: str, target_desktop: Optional[str] = None, target_kernel: Optional[str] = None, target_bootloader: Optional[str] = None, package_profiles: Optional[List[str]] = None, service_profiles: Optional[List[str]] = None, target_live_profile: Optional[str] = None, live_user: Optional[str] = None, live_groups: Optional[List[str]] = None, platforms: Optional[List[str]] = None) -> Config: Assembles and merges configuration profiles into a unified Config object.

  • validate(target_arch: str, target_desktop: Optional[str] = None, target_kernel: Optional[str] = None, target_bootloader: Optional[str] = None, package_profiles: Optional[List[str]] = None, service_profiles: Optional[List[str]] = None) -> Dict[str, Any]: Validates component profile existence and returns structured audit report {"valid": bool, "errors": list, "summary": dict}.

Module: void_builder.core.orchestrator

Class BuildOrchestrator(...)

High-level build controller coordinating configuration assembly, toolchain setup, chroot creation, and image generation.

Methods

  • validate() -> Dict[str, Any]: Runs configuration validation without executing build pipeline.

  • run_build(output_iso: str, output_format: str = "iso") -> Path: Executes the complete build workflow and returns output file path.

Module: void_builder.core.iso_engine

Class ISOEngine

Abstract base class and registry for architecture build engines.

Registered Engines

  • @ISOEngine.register("x86_64") / @ISOEngine.register("i686") / @ISOEngine.register("aarch64"): VoidEngine

  • @ISOEngine.register("rpi-aarch64") / @ISOEngine.register("pinebookpro") / @ISOEngine.register("asahi"): PlatformEngine

Class BaseEngine(arch, config, toolchain)

Abstract engine providing core utility functions.

Methods

  • setup_workdir(workdir: Optional[Union[str, Path]] = None) -> Path: Resolves writable workspace directory.

  • _generate_manifest_and_checksums(output_file_path: str) -> None: Calculates SHA256/MD5 hashes and writes manifest.json.

  • export_tarball(output_path: str) -> str: Compresses rootfs into .tar.xz archive.

Class VoidEngine

Engine handling standard PC ISO 9660 hybrid image creation.

Methods

  • setup_chroot(workdir: str) -> None: Prepares airootfs and iso-staging directories.

  • install_packages() -> None: Invokes ChrootManager to install target packages.

  • post_install_configure() -> None: Applies locale, user, service, and Plymouth customizations.

  • build_bootloaders(mountpoint: str) -> None: Assembles SYSLINUX and GRUB EFI boot files.

  • finalize_isofile(output_path: str) -> None: Runs mksquashfs and xorriso to create final .iso.

Class PlatformEngine

Engine handling SBC raw disk image generation.

Methods

  • finalize_isofile(output_path: str) -> None: Calculates required rootfs size, formats disk image with sfdisk, mounts loop device, copies rootfs, and writes U-Boot/GRUB EFI binaries.

Module: void_builder.core.chroot_manager

Class ChrootManager(chroot_path, toolchain, mode, arch, config)

Manages virtual filesystem mounting (/proc, /sys, /dev), xbps-install commands, and user/service setup inside target chroot.

Methods

  • mount() -> None: Mounts pseudo-filesystems.

  • umount() -> None: Safely unmounts pseudo-filesystems.

  • install_packages(package_plan: Dict[str, List[str]], repos: Optional[List[str]] = None) -> None: Executes xbps-install for package set.

  • run_command(cmd: str, check: bool = True) -> subprocess.CompletedProcess: Runs command inside chroot environment.

  • run_reconfigure() -> None: Executes Void 3-pass xbps-reconfigure -a.

Module: void_builder.core.customizer

Class SystemConfigurator(chroot_manager)

Applies low-level Linux system customizations inside target rootfs.

Methods

  • load_from_config(config: Config) -> None: Loads hostname, locale, timezone, users, services, Plymouth, and Dracut configurations.

  • apply() -> None: Executes customization steps sequentially.